<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Control</title>
<meta http-equiv="Content-Type" Content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../styles/styles.css">
<script language="javascript" src='../links.js' type="text/javascript"></script>
</head>
<body>

<h1>Control</h1>
<div class=navbar>
<a href="../index.html">main</a> |
<a href="index.html">service functions</a><br>
</div>

<div class=shortdescr>
The <dfn>Control</dfn> function allows to request misc information and
perform various control actions for the panels and the command line.
</div>

<pre class=syntax>
int WINAPI Control(
  HANDLE hPlugin,
  int Command,
  void *Param
);
</pre>

<h3>Parameters</h3>
<div class=descr>
  <div class=dfn>hPlugin</div>
  <div class=dfndescr>Current plugin instance handle.
    To request information about the active panel set this parameter to
    <code>INVALID_HANDLE_VALUE</code>. This allows to use this function in plugin commands that
    work without creating new panel. The <code>INVALID_HANDLE_VALUE</code> is also used with
    none plugin panels.</div>

  <div class=dfn>Command</div>
  <div class=dfndescr>Control command type. Can be one of the following values (<a name="FILE_CONTROL_COMMANDS">FILE_CONTROL_COMMANDS</a> enum):

<table class="cont">
<tr class="cont"><th class="cont" width="40%">Command</th><th class="cont" width="60%">Description</th></tr>
      <!-- panel -->
<tr class="cont"><th class="cont" width="100%" colspan="2"><b>Panel</b></th></tr>
      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_CHECKPANELSEXIST">FCTL_CHECKPANELSEXIST</a></td>
      <td class="cont" width="60%">Checks if the file panels exist.<br>
        Param must be equal to 0 (unused).<br>
        The function returns <code>FALSE</code> if FAR was started with the /e or /v command line
        arguments (as an external viewer or editor). In this mode the panels are not created.
        <p class=note><img src="../../images/note.gif" alt="Remarks for FCTL_CHECKPANELSEXIST" width="10" height="10"> Attention!</p>
        <UL class=note><LI>
        When FAR is started with the /e or /v command line arguments, this
        function processes only one command - <dfn>FCTL_CHECKPANELSEXIST</dfn>.
        </LI></UL>
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_CLOSEPLUGIN">FCTL_CLOSEPLUGIN</a></td>
      <td class="cont" width="60%">Closes the current plugin.<br>
        <var>Param</var> points to the name of the directory that will be set in the panel after closing the plugin.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_GETPANELINFO">FCTL_GETPANELINFO</a><br>
      <a name="FCTL_GETANOTHERPANELINFO">FCTL_GETANOTHERPANELINFO</a></td>
      <td class="cont" width="60%">Gets information about a plugin active/passive panel.<br>
        <var>Param</var> points to a <a href="../structures/panelinfo.html">PanelInfo</a> structure that will receive panel information.<br>
        If no items are selected in panel, PanelInfo.SelectedItemsNumber is equal to 1 and
        PanelInfo.SelectedItems contains data for the item under cursor. In order to verify whether
        the file is actually selected, check if the <a href="../structures/pluginpanelitem.html#PPIF_SELECTED">PPIF_SELECTED</a>
        flag is set for that item.
        <p>While processing the following request
<pre class=code>Info.Control(INVALID_HANDLE_VALUE,
             FCTL_GETPANELINFO,
             &amp;PInfo);</pre>
        FAR call the <a href="../exported_functions/getopenplugininfo.html">GetOpenPluginInfo</a>
        exported function of the plugin to which the panel belongs. FAR contains a protection
        against an endless recursion in the case when the plugin, from inside the
        <code>GetOpenPluginInfo()</code> function, also calls
        <code>Info.Control(...,FCTL_GETPANELINFO)</code>, the secondary call
        of <code>GetOpenPluginInfo()</code> will not happen.
        <p>In some cases (e.g. searching in archives by <kbd>Alt-F7</kbd>)
        the plugin panel is not really created, for that reason you must check the return value of
        the <dfn>Control</dfn> function, as to not crash in the most unfitting moment by working on
        an none existing panel.
        <p class=note><img src="../../images/note.gif" alt="Remarks for FCTL_GET[ANOTHER]PANELINFO" width="10" height="10"> Attention!</p>
        <UL class=note><LI>
        The PanelItems and SelectedItems fields of the <a href="../structures/panelinfo.html">PanelInfo</a> structure
        will have different addresses after each new call of <dfn>FCTL_GETPANELINFO</dfn> or
        <dfn>FCTL_GETANOTHERPANELINFO</dfn>.
        </LI></UL>
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_GETPANELSHORTINFO">FCTL_GETPANELSHORTINFO</a><br>
      <a name="FCTL_GETANOTHERPANELSHORTINFO">FCTL_GETANOTHERPANELSHORTINFO</a></td>
      <td class="cont" width="60%">Similar to FCTL_GETPANELINFO/FCTL_GETANOTHERPANELINFO, but the PanelItems
       and the SelectedItems fields of the <a href="../structures/panelinfo.html">PanelInfo</a>
       structure are not filled and are set to <code>NULL</code>. This command is intended to be
       used when only the common information about the active/passive panel is needed, without
       any concrete information on elements in that panel.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_REDRAWPANEL">FCTL_REDRAWPANEL</a><br>
      <a name="FCTL_REDRAWANOTHERPANEL">FCTL_REDRAWANOTHERPANEL</a></td>
      <td class="cont" width="60%">Redraws the plugin active/passive panel.<br>
        <var>Param</var> can be either
        <code>NULL</code> or the address of a <a href="../structures/panelredrawinfo.html">PanelRedrawInfo</a>
        structure, so you can set a new cursor position and the top element for that panel. If
        <var>Param</var> is set to NULL, the cursor position and the top element will not be changed.<br>
        If <var>hPlugin</var> equals INVALID_HANDLE_VALUE, then the active panel will be redrawn no
        matter what command was used by the plugin.<br>
        The panel will be redrawn only if that panel is visible at the moment.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_SETNUMERICSORT">FCTL_SETNUMERICSORT</a><br>
      <a name="FCTL_SETANOTHERNUMERICSORT">FCTL_SETANOTHERNUMERICSORT</a></td>
      <td class="cont" width="60%">Sets <a href="../dict.html#numericsort">numeric sort</a> mode for the active/passive panel.<br>
        <var>Param</var> points to an integer value:
        0 (turn numeric sort off) or 1 (turn numeric sort on).<br>
        Setting <var>Param</var> to NULL is equivalent to setting the numeric sort off.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_SETPANELDIR">FCTL_SETPANELDIR</a><br>
      <a name="FCTL_SETANOTHERPANELDIR">FCTL_SETANOTHERPANELDIR</a></td>
      <td class="cont" width="60%">Sets the current directory of a plugin active/passive panel.<br>
        <var>Param</var> points to the directory name. If the plugin supports its own panel, it
        will be closed after execution of this command.
        <p>Note that this function resets the file selection in a directory and makes it impossible
        to restore by pressing <kbd>Ctrl-M</kbd>, even if the directory passed to this function is
        the same as the current directory.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_SETSELECTION">FCTL_SETSELECTION</a><br>
      <a name="FCTL_SETANOTHERSELECTION">FCTL_SETANOTHERSELECTION</a></td>
      <td class="cont" width="60%">Sets active/passive panel items selection.<br>
        <var>Param</var> points to the
        <a href="../structures/panelinfo.html">PanelInfo</a> structure filled by a previous
        FCTL_GETPANELINFO or FCTL_GETANOTHERPANELINFO call. You must not use
        any other <dfn>Control</dfn> functions between FCTL_GETPANELINFO and FCTL_SETSELECTION.
        <p>To change selection, set or clear PPIF_SELECTED flag in the items of the array pointed
        to by the <dfn>PanelItems</dfn> member of the <a href="../structures/panelinfo.html">PanelInfo</a>
        structure. Note that FCTL_GETPANELINFO and FCTL_GETANOTHERPANELINFO return PPIF_SELECTED in
        this array set to its real state.
        <p>You need to call FCTL_REDRAWPANEL to show the changes.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_SETSORTMODE">FCTL_SETSORTMODE</a><br>
      <a name="FCTL_SETANOTHERSORTMODE">FCTL_SETANOTHERSORTMODE</a></td>
      <td class="cont" width="60%">Sets the active/passive panel sort mode.<br>
        <var>Param</var> points to an
        integer containing the new sort mode (see "<a href="../defs/sortmetods.html">Sort modes</a>").
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_SETSORTORDER">FCTL_SETSORTORDER</a><br>
      <a name="FCTL_SETANOTHERSORTORDER">FCTL_SETANOTHERSORTORDER</a></td>
      <td class="cont" width="60%">Sets the active/passive panel sort order.<br>
        <var>Param</var> points to an
        integer value representing the sort order: 0 for normal order or 1 for reverse order.<br>
        Setting <var>Param</var> to NULL is equivalent to setting the normal sort order (0).
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_SETVIEWMODE">FCTL_SETVIEWMODE</a><br>
      <a name="FCTL_SETANOTHERVIEWMODE">FCTL_SETANOTHERVIEWMODE</a></td>
      <td class="cont" width="60%">Sets active/passive panel view mode.<br>
        <var>Param</var> points to an integer
        containing the new view mode number, from 0 to 9.<br>
        Setting <var>Param</var> to NULL is equivalent to setting mode 0.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_UPDATEPANEL">FCTL_UPDATEPANEL</a><br>
      <a name="FCTL_UPDATEANOTHERPANEL">FCTL_UPDATEANOTHERPANEL</a></td>
      <td class="cont" width="60%">Updates plugin active/passive panel contents.<br>
        If <var>Param</var> is <code>NULL</code>, the file selection will be cleared, otherwise selection is not changed.
      </td></tr>

      <!-- command line -->
<tr class="cont"><th class="cont" width="100%" colspan="2"><b>Command line</b></th></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_GETCMDLINE">FCTL_GETCMDLINE</a></td>
      <td class="cont" width="60%">Gets the command line contents.<br>
        <var>Param</var> points to the buffer to receive data (the buffer should not be smaller than 1 Kb).
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_GETCMDLINEPOS">FCTL_GETCMDLINEPOS</a></td>
      <td class="cont" width="60%">Gets the cursor position in the command line.<br>
        <var>Param</var> points to a variable of type int that receives the cursor position.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_GETCMDLINESELECTEDTEXT">FCTL_GETCMDLINESELECTEDTEXT</a></td>
      <td class="cont" width="60%">Retrieves the selected text in the command line.<br>
       <var>Param</var> points to the buffer to receive data (the buffer should not be smaller than 1 Kb).
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_GETCMDLINESELECTION">FCTL_GETCMDLINESELECTION</a></td>
      <td class="cont" width="60%">Returns the parameters of the text selection in the command line.<br>
        <var>Param</var> points to a <a href="../structures/cmdlineselect.html">CmdLineSelect</a> structure.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_INSERTCMDLINE">FCTL_INSERTCMDLINE</a></td>
      <td class="cont" width="60%">Inserts text into the command line beginning from the current cursor position.<br>
        <var>Param</var> points to a zero terminated string to insert to the command line.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_SETCMDLINE">FCTL_SETCMDLINE</a></td>
      <td class="cont" width="60%">Sets the command line contents.<br>
       <var>Param</var> points to a zero terminated string to copy to the command line.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_SETCMDLINEPOS">FCTL_SETCMDLINEPOS</a></td>
      <td class="cont" width="60%">Sets the cursor position in the command line.<br>
        <var>Param</var> points to a variable of type int that contains the new cursor position.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_SETCMDLINESELECTION">FCTL_SETCMDLINESELECTION</a></td>
      <td class="cont" width="60%">Selects a text fragment in the command line.<br>
        <var>Param</var> points to a <a href="../structures/cmdlineselect.html">CmdLineSelect</a> structure.
      </td></tr>

      <!-- other -->
<tr class="cont"><th class="cont" width="100%" colspan="2"><b>Other</b></th></tr>
      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_SETUSERSCREEN">FCTL_SETUSERSCREEN</a></td>
      <td class="cont" width="60%">Copies the current screen contents to the FAR user screen buffer (which
        is displayed when the panels are switched off).<br>
        <var>Param</var> must be <code>NULL</code>.
      </td></tr>

      <tr class="cont"><td class="cont" width="40%"><a name="FCTL_GETUSERSCREEN">FCTL_GETUSERSCREEN</a></td>
      <td class="cont" width="60%">Outputs the FAR user screen buffer (which
        is displayed when the panels are switched off) to the screen.<br>
        <var>Param</var> must be <code>NULL</code>.
      </td></tr>

</table>
  </div>
  <div class=dfn>Param</div>
  <div class=dfndescr>Points to control command parameters. Read the description of the
  <dfn>Command</dfn> parameter for concrete information.
  </div>

</div>

<h3>Return value</h3>
<div class=descr>
  If the function succeeds, the return value is TRUE. If the function fails, FALSE is returned.
</div>

<h3>Remarks</h3>
<div class=descr>
  Usually you do not need to update or redraw panel and close plugin directly. FAR does this
  itself, when performing standard operations. These functions can become necessary to implement
  some non-standard functionality.
</div>

<div class=see>See also:</div><div class=seecont>
<a href="advcontrol.html">AdvControl</a>,
<a href="editorcontrol.html">EditorControl</a>
</div>

</body>
</html>